Work Item / Issue Reference

GitHub Issue: #352

Summary

This PR fixes cursor.description to properly return SQL type codes per DB-API 2.0 specification, while maintaining backwards compatibility with libraries like pandas and polars that compare against Python types.

The original issue was reported when using polars pl.read_database() which failed with:

ComputeError: could not append value: 2013-01-01 of type: date to the builder

Key Changes

1. New SqlTypeCode Class

A dual-compatible type code that compares equal to both:

• SQL type integers (e.g., desc[1] == -9) for DB-API 2.0 compliance
• Python types (e.g., desc[1] == str) for pandas/polars/library compatibility

cursor.execute("SELECT id, name FROM users")
desc = cursor.description

# Style 1: Compare with Python types (pandas/polars compatibility)
if desc[0][1] == int:
    print("Integer column")

# Style 2: Compare with SQL type codes (DB-API 2.0)
if desc[0][1] == 4:  # SQL_INTEGER
    print("Integer column")

# Get raw SQL type code
type_code = int(desc[0][1])  # Returns 4 for SQL_INTEGER

2. SQL Server Spatial Type Support

Added handling for SQL Server User-Defined Types (SQL_SS_UDT = -151):

• geography (e.g., GPS coordinates, regions)
• geometry (e.g., shapes, planar coordinates)
• hierarchyid (e.g., org charts, tree structures)

3. ODBC 3.x Date/Time Type Codes

Added support for:

• SQL_TYPE_DATE (91)
• SQL_TYPE_TIME (92)
• SQL_TYPE_TIMESTAMP (93)
• SQL_TYPE_TIMESTAMP_WITH_TIMEZONE (95)

4. Hash/Equality Contract Fix

Made SqlTypeCode intentionally unhashable since __eq__ compares to multiple types with different hash values. Attempting to hash raises TypeError with a helpful message guiding users to use int(type_code) as dict keys instead.

Files Changed

Usage Examples

SqlTypeCode - Dual Compatibility

cursor.execute("SELECT id, name FROM users")
desc = cursor.description

# Style 1: Compare with Python types (pandas/polars compatibility)
if desc[0][1] == int:
    print("Integer column")

# Style 2: Compare with SQL type codes (DB-API 2.0)
if desc[0][1] == 4:  # SQL_INTEGER
    print("Integer column")

# Get raw SQL type code
type_code = int(desc[0][1])  # Returns 4 for SQL_INTEGER

Polars Integration (Original Issue)

import polars as pl
import mssql_python

conn = mssql_python.connect("Server=myserver;Database=mydb;...")

# This now works correctly!
df = pl.read_database(
    query="SELECT * FROM Sales.Customers",
    connection=conn
)
print(df)

Spatial Types

# Geography (GPS coordinates)
cursor.execute("""
    INSERT INTO locations (geo) 
    VALUES (geography::STGeomFromText('POINT(-122.349 47.651)', 4326))
""")

# Fetch as binary
cursor.execute("SELECT geo FROM locations")
geo_bytes = cursor.fetchone()[0]  # Returns bytes

# Or fetch as WKT text
cursor.execute("SELECT geo.STAsText() FROM locations")
wkt = cursor.fetchone()[0]  # Returns "POINT (-122.349 47.651)"

Testing

Test Coverage

• ✅ All existing tests pass (1425 passed)
• ✅ 18 new SqlTypeCode unit tests
• ✅ 37 new spatial type tests (geography, geometry, hierarchyid)
• ✅ 6 new polars integration tests
• ✅ Thread safety tests for _column_metadata
• ✅ Binary parameter round-trip tests for spatial types
• 📊 Diff Coverage: 93%
• 📊 Overall Coverage: 77%

Polars Integration Tests

Breaking Changes

None. The SqlTypeCode class maintains full backwards compatibility:

• ✅ cursor.description[i][1] == str still works
• ✅ cursor.description[i][1] == -9 also works
• ✅ int(cursor.description[i][1]) returns raw SQL type code

Related Issues

• Fixes Cursor.description returning incorrect values #352 - Cursor.description returning incorrect values